/*
 *  Copyright (C) 2010 glauco
 * 
 *  This program is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or
 *  (at your option) any later version.
 * 
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 * 
 *  You should have received a copy of the GNU General Public License
 *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

package org.balisunrise.common;

/**
 * Objetos desta interface implementam a ação de selecionar uma entidade.<br>
 * <br>
 * SelectionAction possui uma representação visual que ativa uma ação que
 * deve mostrar uma busca (<code>Search</code>) onde o usuário irá selecionar
 * uma entidade, a qual será atribuída ao <code>SelectionPanelGroup</code>.<br>
 * O <code>Search</code> é construído utilizando o SearchBuilder do Application
 * e mostrado na tela pelo ViewManager.
 * Se nenhuma entidade for selecionada depois de mostrar a busca, é mostrado
 * a mensagem de notFoundMessage.<br>
 * Se foi selecionado alguma entidade o Focus deve ir para o último componente
 * Criterionable do selectionPanelGroup, caso contrário deve ir para primeiro
 * componente Criterionable.<br>
 * <br>
 * SelectionAction também implementa a ação de selecionar uma entidade ao focus
 * pelo último componente Criterionable do selectionPanelGroup.<br>
 * Esta segunda ação deve ser disparada só deve ser disparada quando algum
 * Criterionable for modificado.<br>
 * O SelectionAction constrói um <code>EntitySelection</code> utilizando o
 * Builder do Application e mostra na tela pelo ViewManager.<br>
 * As condições para listagem do EntitySelection são os Criterionable do 
 * selectionPanelGroup.<br>
 * Caso a listagem não retorne resultados, deve ser mostrada a mensagem de 
 * notFoundMessage.<br>
 * Caso a listagem retorne apenas um resultado, ele deve ser atribuído 
 * diretamente ao <code>SelectionPanelGroup</code> e não deve ser mostrado o
 * <code>EntitySelection</code>. As outras condições da seleção da entidade pelo
 * <code>EntitySelection</code> são as mesmas do <code>Search</code>.
 * 
 * @author glauco
 * @see org.balisunrise.common.Search
 * @see org.balisunrise.application.Application
 * @see org.balisunrise.builder.SearchBuilder
 * @see org.balisunrise.common.SelectionPanelGroup
 * @see org.balisunrise.application.ViewManager
 * @see org.balisunrise.common.Criterionable
 * @see org.balisunrise.common.EntitySelection
 */
public interface SelectionAction<T> extends FieldAction<T>{

    /**
     * Retorna a classe do qual o campo pertense.
     * Esta é a classe da entidade da qual a pesquisa (seleção).
     */
    @Override
    public Class getEntityClass();

    /**
     * Retorna o alias da busca.
     * @param searchAlias
     */
    public String getSearchAlias();

    /**
     * Atribui a mensagem para quando as entidades não forem encontradas.
     * @param notFoundMessage
     */
    public String getNotFoundMessage();

    /**
     * Atribui o grupo de seleção.
     * @param selectionFieldLayout
     */
    public void setSelectionFieldLayout(SelectionFieldLayout selectionFieldLayout);
}
